 /*
  * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationAdmin.java,v 1.16 2006/07/11 00:54:03 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.osgi.service.cm;

 import java.io.IOException ;
 import java.util.Dictionary ;

 import org.osgi.framework.InvalidSyntaxException;

 /**
  * Service for administering configuration data.
  *
  * <p>
  * The main purpose of this interface is to store bundle configuration data
  * persistently. This information is represented in <code>Configuration</code>
  * objects. The actual configuration data is a <code>Dictionary</code> of
  * properties inside a <code>Configuration</code> object.
  *
  * <p>
  * There are two principally different ways to manage configurations. First
  * there is the concept of a Managed Service, where configuration data is
  * uniquely associated with an object registered with the service registry.
  *
  * <p>
  * Next, there is the concept of a factory where the Configuration Admin service
  * will maintain 0 or more <code>Configuration</code> objects for a Managed
  * Service Factory that is registered with the Framework.
  *
  * <p>
  * The first concept is intended for configuration data about "things/services"
  * whose existence is defined externally, e.g. a specific printer. Factories are
  * intended for "things/services" that can be created any number of times, e.g.
  * a configuration for a DHCP server for different networks.
  *
  * <p>
  * Bundles that require configuration should register a Managed Service or a
  * Managed Service Factory in the service registry. A registration property
  * named <code>service.pid</code> (persistent identifier or PID) must be used
  * to identify this Managed Service or Managed Service Factory to the
  * Configuration Admin service.
  *
  * <p>
  * When the ConfigurationAdmin detects the registration of a Managed Service, it
  * checks its persistent storage for a configuration object whose PID matches
  * the PID registration property (<code>service.pid</code>) of the Managed
  * Service. If found, it calls {@link ManagedService#updated} method with the
  * new properties. The implementation of a Configuration Admin service must run
  * these call-backs asynchronously to allow proper synchronization.
  *
  * <p>
  * When the Configuration Admin service detects a Managed Service Factory
  * registration, it checks its storage for configuration objects whose
  * <code>factoryPid</code> matches the PID of the Managed Service Factory. For
  * each such <code>Configuration</code> objects, it calls the
  * <code>ManagedServiceFactory.updated</code> method asynchronously with the
  * new properties. The calls to the <code>updated</code> method of a
  * <code>ManagedServiceFactory</code> must be executed sequentially and not
  * overlap in time.
  *
  * <p>
  * In general, bundles having permission to use the Configuration Admin service
  * can only access and modify their own configuration information. Accessing or
  * modifying the configuration of another bundle requires
  * <code>ConfigurationPermission[*,CONFIGURE]</code>.
  *
  * <p>
  * <code>Configuration</code> objects can be <i>bound </i> to a specified
  * bundle location. In this case, if a matching Managed Service or Managed
  * Service Factory is registered by a bundle with a different location, then the
  * Configuration Admin service must not do the normal callback, and it should
  * log an error. In the case where a <code>Configuration</code> object is not
  * bound, its location field is <code>null</code>, the Configuration Admin
  * service will bind it to the location of the bundle that registers the first
  * Managed Service or Managed Service Factory that has a corresponding PID
  * property. When a <code>Configuration</code> object is bound to a bundle
  * location in this manner, the Confguration Admin service must detect if the
  * bundle corresponding to the location is uninstalled. If this occurs, the
  * <code>Configuration</code> object is unbound, that is its location field is
  * set back to <code>null</code>.
  *
  * <p>
  * The method descriptions of this class refer to a concept of "the calling
  * bundle". This is a loose way of referring to the bundle which obtained the
  * Configuration Admin service from the service registry. Implementations of
  * <code>ConfigurationAdmin</code> must use a
  * {@link org.osgi.framework.ServiceFactory} to support this concept.
  *
  * @version $Revision: 1.16 $
  */
 public interface ConfigurationAdmin {
     /**
      * Service property naming the Factory PID in the configuration dictionary.
      * The property's value is of type <code>String</code>.
      *
      * @since 1.1
      */
     public final static String SERVICE_FACTORYPID = "service.factoryPid";
     /**
      * Service property naming the location of the bundle that is associated
      * with a a <code>Configuration</code> object. This property can be
      * searched for but must not appear in the configuration dictionary for
      * security reason. The property's value is of type <code>String</code>.
      *
      * @since 1.1
      */
     public final static String SERVICE_BUNDLELOCATION = "service.bundleLocation";

     /**
      * Create a new factory <code>Configuration</code> object with a new PID.
      *
      * The properties of the new <code>Configuration</code> object are
      * <code>null</code> until the first time that its
      * {@link Configuration#update(Dictionary)} method is called.
      *
      * <p>
      * It is not required that the <code>factoryPid</code> maps to a
      * registered Managed Service Factory.
      * <p>
      * The <code>Configuration</code> object is bound to the location of the
      * calling bundle.
      *
      * @param factoryPid PID of factory (not <code>null</code>).
      * @return A new <code>Configuration</code> object.
      * @throws IOException if access to persistent storage fails.
      * @throws SecurityException if caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code> and <code>factoryPid</code> is bound to another bundle.
      */
     public Configuration createFactoryConfiguration(String factoryPid)
             throws IOException ;

     /**
      * Create a new factory <code>Configuration</code> object with a new PID.
      *
      * The properties of the new <code>Configuration</code> object are
      * <code>null</code> until the first time that its
      * {@link Configuration#update(Dictionary)} method is called.
      *
      * <p>
      * It is not required that the <code>factoryPid</code> maps to a
      * registered Managed Service Factory.
      *
      * <p>
      * The <code>Configuration</code> is bound to the location specified. If
      * this location is <code>null</code> it will be bound to the location of
      * the first bundle that registers a Managed Service Factory with a
      * corresponding PID.
      *
      * @param factoryPid PID of factory (not <code>null</code>).
      * @param location A bundle location string, or <code>null</code>.
      * @return a new <code>Configuration</code> object.
      * @throws IOException if access to persistent storage fails.
      * @throws SecurityException if caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code>.
      */
     public Configuration createFactoryConfiguration(String factoryPid, String location)
             throws IOException ;

     /**
      * Get an existing <code>Configuration</code> object from the persistent
      * store, or create a new <code>Configuration</code> object.
      *
      * <p>
      * If a <code>Configuration</code> with this PID already exists in
      * Configuration Admin service return it. The location parameter is ignored
      * in this case.
      *
      * <p>
      * Else, return a new <code>Configuration</code> object. This new object
      * is bound to the location and the properties are set to <code>null</code>.
      * If the location parameter is <code>null</code>, it will be set when a
      * Managed Service with the corresponding PID is registered for the first
      * time.
      *
      * @param pid Persistent identifier.
      * @param location The bundle location string, or <code>null</code>.
      * @return An existing or new <code>Configuration</code> object.
      * @throws IOException if access to persistent storage fails.
      * @throws SecurityException if the caller does not have <code>ConfigurationPermission[*,CONFIGURE]</code>.
      */
     public Configuration getConfiguration(String pid, String location)
             throws IOException ;

     /**
      * Get an existing or new <code>Configuration</code> object from the
      * persistent store.
      *
      * If the <code>Configuration</code> object for this PID does not exist,
      * create a new <code>Configuration</code> object for that PID, where
      * properties are <code>null</code>. Bind its location to the calling
      * bundle's location.
      *
      * <p>
      * Otherwise, if the location of the existing <code>Configuration</code> object
      * is <code>null</code>, set it to the calling bundle's location.
      *
      * @param pid persistent identifier.
      * @return an existing or new <code>Configuration</code> matching the PID.
      * @throws IOException if access to persistent storage fails.
      * @throws SecurityException if the <code>Configuration</code> object is bound to a location different from that of the calling bundle and it has no <code>ConfigurationPermission[*,CONFIGURE]</code>.
      */
     public Configuration getConfiguration(String pid) throws IOException ;

     /**
      * List the current <code>Configuration</code> objects which match the
      * filter.
      *
      * <p>
      * Only <code>Configuration</code> objects with non- <code>null</code>
      * properties are considered current. That is,
      * <code>Configuration.getProperties()</code> is guaranteed not to return
      * <code>null</code> for each of the returned <code>Configuration</code>
      * objects.
      *
      * <p>
      * Normally only <code>Configuration</code> objects that are bound to the
      * location of the calling bundle are returned, or all if the caller has
      * <code>ConfigurationPermission[*,CONFIGURE]</code>.
      *
      * <p>
      * The syntax of the filter string is as defined in the <code>Filter</code>
      * class. The filter can test any configuration parameters including the
      * following system properties:
      * <ul>
      * <li><code>service.pid</code>-<code>String</code>- the PID under
      * which this is registered</li>
      * <li><code>service.factoryPid</code>-<code>String</code>- the
      * factory if applicable</li>
      * <li><code>service.bundleLocation</code>-<code>String</code>- the
      * bundle location</li>
      * </ul>
      * The filter can also be <code>null</code>, meaning that all
      * <code>Configuration</code> objects should be returned.
      *
      * @param filter a <code>Filter</code> object, or <code>null</code> to
      * retrieve all <code>Configuration</code> objects.
      * @return all matching <code>Configuration</code> objects, or
      * <code>null</code> if there aren't any
      * @throws IOException if access to persistent storage fails
      * @throws InvalidSyntaxException if the filter string is invalid
      */
     public Configuration[] listConfigurations(String filter) throws IOException ,
             InvalidSyntaxException;
 }

